{% extends "layout.html" %}
{% load static %}

{% block title %}
    API — {{ block.super }}
{% endblock %}

{% block content %}
    <div class="content">
        <div class="form-title">🤖<br>Мои приложения</div>

        <div class="block apps">
            {% if apps %}
                <div class="apps-list">
                    {% for app in apps %}
                        <a href="{% url "edit_app" app.id %}" class="block apps-list-item">
                            <span class="apps-list-item-name">{{ app.name }}</span>
                            <span class="apps-list-item-description">{{ app.description }}</span>
                        </a>
                    {% endfor %}
                </div>
            {% else %}
                <div class="apps-list-placeholder">
                    У вас нет ни одного приложения.<br>
                    Но если вы чувствуете себя программистом — можете создать.
                </div>
            {% endif %}

            <div class="apps-list-create-button">
                <a href="{% url "create_app" %}" class="button">Создать новое приложение</a>
            </div>
        </div>

        <div class="block">
            <div class="block-header block-header-big">🤖 API</div>

            <div class="block-description">
                <p>
                    Наш API еще маленький и глупый, но для простых ботов и интеграций с Клубом его хватает.
                    Основная идея в том, что многие его эндпоинты повторяют обычные URL сайта, но с добавлением .json или .md в конце как расширение.
                    Так легче запомнить.
                </p>

                <p>
                    Если вам нужен новый эндпоинт — вы всегда можете попросить на гитхабе или даже написать его сами. Во славу опенсорса!
                </p>

                <br><br>

                <h2>Фид и посты</h2>

                <p>
                    <a href="{{ settings.APP_HOST }}/feed.json">{{ settings.APP_HOST }}/feed.json</a>
                    — вернёт главную страницу в формате <a href="https://www.jsonfeed.org/version/1.1/" target="_blank">JSON Feed</a>.
                    Возможна пажинация. Эндпоинт открыт на публику (это аналог RSS), однако если запрос идёт от неавторизованного пользователя — контент приватных постов будет скрыт.
                </p>

                <p>
                    <a href="{{ settings.APP_HOST }}/post/top/feed.json">{{ settings.APP_HOST }}/post/top/feed.json</a>
                    — фид, отфильтрованный по типу постов (all, post, question, thread, ...) и отсортированный по одному из критериев (activity, new, hot, top, top_week, top_month, top_year).
                </p>

                <p>
                    <a href="{{ settings.APP_HOST }}/post/2584.json">{{ settings.APP_HOST }}/post/2584.json</a>
                    — получить текст и метаданные конкретного поста в том же формате JSON Feed Item.
                </p>

                <p>
                    <a href="{{ settings.APP_HOST }}/post/2584.md">{{ settings.APP_HOST }}/post/2584.md</a>
                    — вернет текст и заголовок поста в Markdown.
                </p>

                <p>
                    <a href="{{ settings.APP_HOST }}/post/2584/comments.json">{{ settings.APP_HOST }}/post/2584/comments.json</a>
                    — вернёт список комментов к посту в JSON.
                </p>

                <br><br>

                <h2>Юзеры</h2>

                <p>
                    <a href="{{ settings.APP_HOST }}/user/{{ request.me.slug }}.json">{{ settings.APP_HOST }}/user/{{ request.me.slug }}.json</a>
                    — получить данные юзера по никнейму в Клубе.
                </p>

                <p>
                    <a href="{{ settings.APP_HOST }}/user/by_telegram_id/{{ request.me.telegram_id|default:"TG_ID" }}.json">{{ settings.APP_HOST }}/user/by_telegram_id/{{ request.me.telegram_id|default:"TG_ID" }}.json</a>
                    — найти юзера по его Telegram ID (не по нику в телеграме, именно по цифровому ID). Удобно для ботов, чтобы проверять зарегистрирован ли пользователь бота в Клубе.
                </p>

                <p>
                    💡 <strong>Hint:</strong> Чтобы получить данные о себе, можно использовать универсальный юзернейм "me" — <a href="{{ settings.APP_HOST }}/user/me.json">{{ settings.APP_HOST }}/user/me.json</a>
                </p>

                <br><br>

                <h2>Поиск</h2>

                <p>
                    <a href="{{ settings.APP_HOST }}/search/users.json?prefix=vas">{{ settings.APP_HOST }}/search/users.json?prefix=vas</a>
                    — найти юзеров по префиксу никнейма. Используется для автокомплита.
                </p>

                <p>
                    <a href="{{ settings.APP_HOST }}/search/tags.json?group=collectible">{{ settings.APP_HOST }}/search/tags.json?group=collectible</a>
                    — получить теги в группе (collectible, hobbies, personal, club). Можно использовать вместе с ?prefix для автокомплита.
                </p>
            </div>
        </div>

        <div class="block">
            <div class="block-header">🤖️ Авторизация для ботов</div>

            <div class="block-description">
                <p>
                    API-запросы к закрытым постам или профилям юзеров требуют авторизации.
                </p>

                <p>
                    Если вы пишете простого бота, вы можете использовать сервис-токен.
                    Он выдаётся один раз при создании приложения и уникален для него.
                    С ним можно делать запросы к API, как будто вы полноценный пользователь.
                </p>

                <p>
                    ⛔️ Если сервис-токен утечёт — срочно удаляйте приложение и создавайте новое.
                    Токен специально привязан к автору приложения, чтобы вы сразу заметили, когда ваш аккаунт похакают.
                    Так что храните его в секретах, передавайте через env-переменные и никогда не комитьте в открытые репозитории.
                </p>

                <p>
                    Использовать сервис-токен в запросах можно вот так:
                </p>

                <p>
                    <pre><code>curl -H "X-Service-Token: TOKEN" {{ settings.APP_HOST }}/user/me.json</code></pre>
                </p>

                <p>
                    Для простоты дебага есть второй способ — передавать токен в GET-параметре:
                </p>

                <pre><code>curl {{ settings.APP_HOST }}/user/me.json?service_token=TOKEN</code></pre>

                <p>
                    ⚠️ Этот способ не рекомендуется для продакшен приложений.
                    GET-параметры имеют свойство утекать через логи сервера или браузера.
                    Используйте его только для собственных нужд.
                </p>
            </div>
        </div>

        <div class="block">
            <div class="block-header">🪪 OpenID Connect — авторизация людей</div>

            <div class="block-description">
                <p>
                    Чтобы аутентифицировать конкретных юзеров через Клуб, у нас есть OAuth/OpenID провайдер.
                    Такой способ подойдет, если вы делаете сторонний проект типа Сикрет Санты и хотите сделать кнопку «Войти через Вастрик.Клуб».
                </p>

                <p>
                    Пример можно посмотреть у меня в <a href="https://vas3k.blog/login/" target="_blank">блоге</a> (вот <a href="https://github.com/vas3k/vas3k.blog/blob/main/authn/views.py#L27" target="_blank">код</a>).
                </p>

                <p>
                    Протокол стандартный и открытый, так что вы тоже так можете.
                </p>

                <p>
                    <strong>Шаг 0.</strong> Почитайте <a href="https://developer.okta.com/blog/2019/10/21/illustrated-guide-to-oauth-and-oidc" target="_blank">как работают OAuth и OpenID Connect</a>, если еще не знакомы с ними.
                </p>

                <p>
                    <strong>Шаг 1.</strong> Создайте новое <a href="{% url "create_app" %}">приложение</a>.
                    После этого вам дадут Client ID и Secret.
                </p>

                <p>
                    <strong>Шаг 2.</strong> Теперь отправляйтесь в наш гайд по <a href="https://vas3k.club/post/openid/">OpenID в Клубе</a>.
                </p>

                <p>
                    <strong>Шаг 3.</strong> Вы великолепны. У вас есть классический access_token в формате JWT и им можно авторизовать запросы прямо вот так:

                    <p>
                        <pre><code>curl -H "Authorization: Bearer ACCESS_TOKEN" {{ settings.APP_HOST }}/user/me.json</code></pre>
                    </p>
                </p>
            </div>
        </div>

        <div class="block">
            <div class="block-header">👷‍♀️ Код Клуба</div>

            <div class="block-description">
                <p>
                    Исходный код Клуба открыт на гитхабе: <a href="https://github.com/vas3k/vas3k.club" target="_blank">github.com/vas3k/vas3k.club</a>
                </p>

                <p>
                    Можно присылать баги в <a href="https://github.com/vas3k/vas3k.club/issues" target="_blank">Issues</a> или даже сразу фиксить их в <a href="https://github.com/vas3k/vas3k.club/pulls" target="_blank">пулл-реквестах</a>.
                </p>

                <p>
                    Обсуждение разработки и идей — в дев-чате <a href="https://t.me/vas3k_club_dev" target="_blank">t.me/vas3k_club_dev</a>.
                </p>

                <p>
                    Мы в опенсорсе, потому что не скрываем наших алгоритмов. Так, например, любой человек может ознакомиться с <a href="https://github.com/vas3k/vas3k.club/blob/master/posts/views/feed.py" target="_blank">ранжированием</a> на главной, посмотреть <a href="https://github.com/vas3k/vas3k.club/blob/master/users/models/user.py" target="_blank">какие</a> данные мы храним о пользователях или узнать как <a href="https://github.com/vas3k/vas3k.club/blob/master/frontend/static/js/components/PeopleMap.vue" target="_blank">работает</a> карта Клуба.
                </p>

                <p>
                    Форкать Клуб можно, но на свой страх и риск. Движок Клуба слишком сильно захардкожен под наши нужды, так что проще будет найти что-то универсальное.
                </p>
            </div>
        </div>
    </div>
{% endblock %}
